---
title: Astro 렌더링 컨텍스트
sidebar:
  label: 렌더링 컨텍스트
i18nReady: true
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 4
---
import Since from '~/components/Since.astro';
import { Tabs, TabItem } from '@astrojs/starlight/components';
import ReadMore from '~/components/ReadMore.astro';

페이지를 렌더링할 때 Astro는 현재 렌더링에 특정한 런타임 API를 제공합니다. 여기에는 현재 페이지 URL과 같은 유용한 정보와 다른 페이지로 리디렉션하는 등의 작업을 수행하는 API가 포함됩니다.

`.astro` 컴포넌트에서 이 컨텍스트는 `Astro` 전역 객체에서 사용할 수 있습니다. 엔드포인트 함수도 이 동일한 컨텍스트 객체를 첫 번째 인수로 사용하여 호출되며, 그 속성은 Astro 전역 속성을 반영합니다.

일부 속성은 요청 시 렌더링되는 경로에서만 사용할 수 있거나 미리 렌더링된 페이지에서 기능이 제한될 수 있습니다.

`Astro` 전역 객체는 모든 `.astro` 파일에서 사용할 수 있습니다. 정적 또는 라이브 서버 엔드포인트를 제공하려면 [엔드포인트 함수](/ko/guides/endpoints/)에서, 페이지 또는 엔드포인트가 렌더링될 때 동작을 삽입하려면 [미들웨어](/ko/guides/middleware/)에서 `context` 객체를 사용합니다.

## 컨텍스트 객체

다음 프로퍼티는 `Astro` 전역(예: `Astro.props`, `Astro.redirect()`)에서 사용할 수 있으며 엔드포인트 함수 및 미들웨어에 전달되는 컨텍스트 객체(예: `context.props`, `context.redirect()`)에서도 사용할 수 있습니다.

### `props`

`props`는 [컴포넌트 속성](/ko/basics/astro-components/#컴포넌트-props)으로 전달된 값을 포함하는 객체입니다.

```astro {3}
---
// src/components/Heading.astro
const { title, date } = Astro.props;
---
<div>
  <h1>{title}</h1>
  <p>{date}</p>
</div>
```

```astro "title=" "date="
---
// src/pages/index.astro
import Heading from '../components/Heading.astro';
---
<Heading title="My First Post" date="09 Aug 2022" />
```

<ReadMore>[Markdown 및 MDX 레이아웃](/ko/guides/markdown-content/#프런트매터-layout-속성)이 props를 처리하는 방법에 대해 자세히 알아보세요.</ReadMore>

`props` 객체에는 정적 경로를 렌더링할 때 `getStaticPaths()`에서 전달된 모든 `props`도 포함됩니다.

<Tabs>
  <TabItem label="Astro.props">
    ```astro title="src/pages/posts/[id].astro" "props:" {11}
    ---
    export function getStaticPaths() {
      return [
        { params: { id: '1' }, props: { author: 'Blu' } },
        { params: { id: '2' }, props: { author: 'Erika' } },
        { params: { id: '3' }, props: { author: 'Matthew' } }
      ];
    }

    const { id } = Astro.params;
    const { author } = Astro.props;
    ---
    ```
  </TabItem>
  <TabItem label="context.props">
    ```ts title="src/pages/posts/[id].json.ts" "props:" {11-15}
    import type { APIContext } from 'astro';

    export function getStaticPaths() {
      return [
        { params: { id: '1' }, props: { author: 'Blu' } },
        { params: { id: '2' }, props: { author: 'Erika' } },
        { params: { id: '3' }, props: { author: 'Matthew' } }
      ];
    }

    export function GET({ props }: APIContext) {
      return new Response(
        JSON.stringify({ author: props.author }),
      );
    }
    ```
  </TabItem>

</Tabs>
더 보기: [`props`로 데이터 전달](/ko/reference/routing-reference/#props를-사용한-데이터-전달)

### `params`

`params`는 요청과 일치하는 동적 경로 세그먼트의 값을 포함하는 객체입니다. 해당 키는 페이지 또는 엔드포인트 파일 경로의 [매개변수](/ko/guides/routing/#동적-라우트)와 일치해야 합니다.

정적 빌드에서는 [동적 경로](/ko/guides/routing/#동적-라우트)를 미리 렌더링하는데 사용되는 `getStaticPaths()`가 반환하는 `params`가 됩니다.

<Tabs>
  <TabItem label="Astro.params">
    ```astro title="src/pages/posts/[id].astro" {9} "params:"
    ---
    export function getStaticPaths() {
      return [
        { params: { id: '1' } },
        { params: { id: '2' } },
        { params: { id: '3' } }
      ];
    }
    const { id } = Astro.params;
    ---
    <h1>{id}</h1>
    ```
  </TabItem>
  <TabItem label="context.params">
    ```ts title="src/pages/posts/[id].json.ts" "params:" {11-15}
    import type { APIContext } from 'astro';

    export function getStaticPaths() {
      return [
        { params: { id: '1' } },
        { params: { id: '2' } },
        { params: { id: '3' } }
      ];
    }

    export function GET({ params }: APIContext) {
      return new Response(
        JSON.stringify({ id: params.id }),
      );
    }
    ```
  </TabItem>
</Tabs>

경로가 요청 시 렌더링될 때 `params`는 동적 경로 패턴의 경로 세그먼트와 일치하는 임의의 값일 수 있습니다.

```astro title="src/pages/posts/[id].astro" "Astro.params"
---
import { getPost } from '../api';

const post = await getPost(Astro.params.id);

// ID로 게시물을 찾을 수 없는 경우
if (!post) {
  return Astro.redirect("/404")
}
---
<html>
  <h1>{post.name}</h1>
</html>
```

더 보기: [`params`](/ko/reference/routing-reference/#params)

### `url`

<p>

**타입:** `URL`<br />
<Since v="1.0.0" />
</p>

`url`은 현재 `request.url` 값으로 구성된 [URL](https://developer.mozilla.org/ko/docs/Web/API/URL) 객체입니다. pathname 및 origin과 같은 요청 URL의 개별 속성과 상호 작용할 때 유용합니다. 

`Astro.url`은 `new URL(Astro.request.url)`을 수행하는 것과 동일합니다.

개발 모드에서 `url`은 `localhost` URL이 됩니다. 사이트를 빌드할 때 미리 렌더링된 경로는 [`site`](/ko/reference/configuration-reference/#site) 및 [`base`](/ko/reference/configuration-reference/#base) 옵션에 기반한 URL을 받게 됩니다. `site`가 구성되지 않은 경우 미리 렌더링된 페이지도 빌드 중에 `localhost` URL을 받게 됩니다.

```astro title="src/pages/index.astro" "Astro.url"
<h1>The current URL is: {Astro.url}</h1>
<h1>The current URL pathname is: {Astro.url.pathname}</h1>
<h1>The current URL origin is: {Astro.url.origin}</h1>
```

`url`을 [`new URL()`](https://developer.mozilla.org/ko/docs/Web/API/URL/URL)의 인자로 전달하여 새 URL을 만들 수도 있습니다.

```astro title="src/pages/index.astro" "Astro.url"
---
// 예시: 프로덕션 도메인을 사용하여 canonical URL 생성
const canonicalURL = new URL(Astro.url.pathname, Astro.site);
// 예시: 현재 도메인을 사용하여 SEO 메타 태그의 URL 생성
const socialImageURL = new URL('/images/preview.png', Astro.url);
---
<link rel="canonical" href={canonicalURL} />
<meta property="og:image" content={socialImageURL} />
```

### `site`

<p>

**타입:** `URL | undefined`
</p>

`site`는 Astro 구성의 `site`에서 만든 `URL`을 반환합니다. Astro 구성에서 [`site`](/ko/reference/configuration-reference/#site)에 대한 값을 설정하지 않은 경우 `undefined`를 반환합니다.

```astro title="src/pages/index.astro" "Astro.site"
<link
    rel="alternate"
    type="application/rss+xml"
    title="Your Site's Title"
    href={new URL("rss.xml", Astro.site)}
/>
```

### `clientAddress`

<p>

**타입:** `string`<br />
<Since v="1.0.0" />
</p>

`clientAddress`는 요청의 [IP 주소](https://en.wikipedia.org/wiki/IP_address)를 지정합니다. 이 속성은 요청 시 렌더링되는 경로에만 사용할 수 있으며 미리 렌더링된 페이지에는 사용할 수 없습니다.

<Tabs>
  <TabItem label="Astro.clientAddress">
    ```astro title="src/pages/ip-address.astro" "Astro.clientAddress"
    ---
    export const prerender = false; // 'server' 모드에서는 필요하지 않음
    ---

    <div>Your IP address is: <span class="address">{Astro.clientAddress}</span></div>
    ```
  </TabItem>
  <TabItem label="context.clientAddress">
    ```ts title="src/pages/ip-address.ts" "clientAddress"
    export const prerender = false; // 'server' 모드에서는 필요하지 않음
    import type { APIContext } from 'astro';

    export function GET({ clientAddress }: APIContext) {
      return new Response(`Your IP address is: ${clientAddress}`);
    }
    ```
  </TabItem>
</Tabs>

### `isPrerendered`

<p>

**타입**: `boolean`<br />
<Since v="5.0.0" />
</p>

현재 페이지가 미리 렌더링된 페이지인지 여부를 나타내는 부울입니다.

이 속성을 사용하여 미들웨어에서 조건부 로직을 실행할 수 있습니다(예: 미리 렌더링된 페이지의 헤더에 액세스하지 않도록 하기 위해).

### `generator`

<p>

**타입:** `string`<br />
<Since v="1.0.0" />
</p>

`generator`는 프로젝트가 실행 중인 Astro의 현재 버전을 제공합니다. 현재 사용 중인 Astro 버전과 함께 [`<meta name="generator">`](https://html.spec.whatwg.org/multipage/semantics.html#meta-generator) 태그를 추가하는 편리한 방법입니다. 이 태그는 `"Astro v5.x.x"` 형식을 따릅니다.

<Tabs>
  <TabItem label="Astro.generator">
    ```astro title="src/pages/site-info.astro" "Astro.generator"
    <html>
      <head>
        <meta name="generator" content={Astro.generator} />
      </head>
      <body>
        <footer>
          <p>Built with <a href="https://astro.build">{Astro.generator}</a></p>
        </footer>
      </body>
    </html>
    ```
  </TabItem>
  <TabItem label="context.generator">
    ```ts title="src/pages/site-info.json.ts" "generator"
    import type { APIContext } from 'astro';

    export function GET({ generator, site }: APIContext) {
      const body = JSON.stringify({ generator, site });
      return new Response(body);
    }
    ```
  </TabItem>
</Tabs>

### `request`

<p>

**타입:** `Request`
</p>

`request`는 표준 [Request](https://developer.mozilla.org/ko/docs/Web/API/Request) 객체입니다. 요청의 `url`, `headers`, `method`, 본문을 가져오는 데 사용할 수 있습니다. 

<Tabs>
  <TabItem label="Astro.request">
    ```astro wrap title="src/pages/index.astro" "Astro.request"
    <p>Received a {Astro.request.method} request to "{Astro.request.url}".</p>
    <p>Received request headers:</p>
    <p><code>{JSON.stringify(Object.fromEntries(Astro.request.headers))}</code></p>
    ```
  </TabItem>
  <TabItem label="context.request">
    ```ts "request"
    import type { APIContext } from 'astro';

    export function GET({ request }: APIContext) {
      return new Response(`Hello ${request.url}`);
    }
    ```
  </TabItem>
</Tabs>

:::note
미리 렌더링된 페이지에서는 `request.url`에 `?type=new`와 같은 검색 매개변수가 포함되지 않습니다. 정적 빌드 중에 값을 미리 결정할 수 없기 때문입니다. 그러나 요청 시 렌더링되는 페이지에서는 `request.url`에 검색 매개변수가 포함됩니다. 서버 요청으로부터 값을 결정할 수 있기 때문입니다.
:::

### `response`

<p>

**타입:** `ResponseInit & { readonly headers: Headers }`
</p>

`response`는 표준 `ResponseInit` 객체입니다. 다음과 같은 구조를 가집니다. 

 - `status`: 응답의 숫자 상태 코드(예: `200`).
 - `statusText`: 상태 코드와 연관된 상태 메시지(예: `'OK'`).
 - `headers`: 응답의 HTTP 헤더를 설정하는 데 사용할 수 있는 [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers) 인스턴스.

`Astro.response`는 페이지의 응답의 `status`, `statusText`, `headers`를 설정하는 데 사용됩니다.

```astro "Astro.response"
---
if (condition) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Not found';
}
---
```

헤더를 설정할 수도 있습니다:

```astro "Astro.response"
---
Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;');
---
```

### `redirect()`

<p>

**타입:** `(path: string, status?: number) => Response`
<Since v="1.5.0" />
</p>

`redirect()`는 다른 페이지로 리디렉션할 수 있는 [Response](https://developer.mozilla.org/ko/docs/Web/API/Response) 객체를 반환하며, 선택적으로 [HTTP 응답 상태 코드](https://developer.mozilla.org/ko/docs/Web/HTTP/Status#%EB%A6%AC%EB%8B%A4%EC%9D%B4%EB%A0%89%EC%85%98_%EB%A9%94%EC%8B%9C%EC%A7%80)를 두 번째 파라미터로 제공합니다.

리디렉션이 발생하려면 하위 컴포넌트가 아닌 페이지가 `Astro.redirect()`의 결과를 `반환`해야 합니다.

정적으로 생성된 경로에서는 [`<meta http-equiv="refresh">` 태그](https://developer.mozilla.org/ko/docs/Web/HTML/Element/meta#http-equiv)를 사용하여 클라이언트 리디렉션을 생성하며 상태 코드는 지원하지 않습니다.

요청 시 렌더링되는 경로에서는 리디렉션 시 사용자 지정 상태 코드를 설정하는 것이 지원됩니다. 지정하지 않으면 리디렉션은 `302` 상태 코드와 함께 제공됩니다.

다음 예시는 사용자를 로그인 페이지로 리디렉션합니다:

<Tabs>
  <TabItem label="Astro.redirect()">
    ```astro title="src/pages/account.astro" {8} "Astro.redirect"
    ---
    import { isLoggedIn } from '../utils';

    const cookie = Astro.request.headers.get('cookie');

    // 사용자가 로그인하지 않았다면 로그인 페이지로 리디렉션합니다.
    if (!isLoggedIn(cookie)) {
      return Astro.redirect('/login');
    }
    ---
    
    <p>User information</p>
    ```
  </TabItem>
  <TabItem label="context.redirect()">
    ```ts "redirect"
    import type { APIContext } from 'astro';

    export function GET({ redirect, request }: APIContext) {
      const cookie = request.headers.get('cookie');
      if (!isLoggedIn(cookie)) {
        return redirect('/login', 302);
      } else {
        // 사용자의 정보를 반환합니다.
      }
    }
    ```
  </TabItem>
</Tabs>

### `rewrite()`

<p>

**타입:** `(rewritePayload: string | URL | Request) => Promise<Response>`<br />
<Since v="4.13.0" />
</p>

`rewrite()`를 사용하면 브라우저를 새 페이지로 리디렉션하지 않고 다른 URL 또는 경로의 콘텐츠를 제공할 수 있습니다. 

이 메서드는 경로 위치에 대한 문자열, `URL` 또는 `Request`를 받습니다.

명시적 경로를 제공하려면 문자열을 사용합니다:

<Tabs syncKey="rewrite">
  <TabItem label="Astro.rewrite()">
    ```astro title="src/pages/index.astro" "Astro.rewrite"
    ---
    return Astro.rewrite("/login")
    ---
    ```
  </TabItem>
  <TabItem label="context.rewrite()">
    ```ts "rewrite"
    import type { APIContext } from 'astro';

    export function GET({ rewrite }: APIContext) {
      return rewrite('/login');
    }
    ```
  </TabItem>
</Tabs>

리라이트를 위한 URL 경로를 구성해야 한다면 `URL` 타입을 사용합니다. 다음 예시는 상대 `"../"` 경로에서 새 URL을 생성하여 페이지의 상위 경로를 렌더링합니다:

<Tabs syncKey="rewrite">
  <TabItem label="Astro.rewrite()">
    ```astro title="src/pages/blog/index.astro"
    ---
    return Astro.rewrite(new URL("../", Astro.url))
    ---
    ```
  </TabItem>
  <TabItem label="context.rewrite()">
    ```ts
    import type { APIContext } from 'astro';

    export function GET({ rewrite }: APIContext) {
      return rewrite(new URL("../", Astro.url));
    }
    ```
  </TabItem>
</Tabs>

새 경로에 대해 서버로 전송되는 `Request`를 완벽하게 제어하려면 `Request` 타입을 사용합니다. 다음 예시는 상위 페이지를 렌더링하는 요청에 헤더를 포함하여 전송합니다:

<Tabs syncKey="rewrite">
  <TabItem label="Astro.rewrite()">
    ```astro title="src/pages/blog/index.astro"
    ---
    return Astro.rewrite(new Request(new URL("../", Astro.url), {
      headers: {
        "x-custom-header": JSON.stringify(Astro.locals.someValue)
      }
    }))
    ---
    ```
  </TabItem>
  <TabItem label="context.rewrite()">
    ```ts
    import type { APIContext } from 'astro';

    export function GET({ rewrite }: APIContext) {
      return rewrite(new Request(new URL("../", Astro.url), {
        headers: {
          "x-custom-header": JSON.stringify(Astro.locals.someValue)
        }
      }));
    }
    ```
  </TabItem>
</Tabs>

### `originPathname`

<p>

**타입:** `string`<br />
<Since v="5.0.0" />
</p>

`originPathname`은 URL 재작성 (Rewrite)이 적용되기 전 요청의 원래 경로 이름을 정의합니다.

<Tabs>
  <TabItem label="Astro.originPathname">
  	```astro title="src/pages/404.astro"
    <p>원래 경로 이름은 {Astro.originPathname}</p>
    <p>다시 작성된 경로는 {Astro.url.pathname}</p>
    ```
  </TabItem>
  <TabItem label="context.originPathname">
    ```ts title="src/middleware.ts"
    import { defineMiddleware } from 'astro:middleware';

    export const onRequest = defineMiddleware(async (context, next) => {
      // URL을 다시 작성하기 전에 원래 경로 이름을 기록합니다.
      recordPageVisit(context.originPathname);
      return next();
    });
  ```
  </TabItem>
</Tabs>

### `locals`

<p>

<Since v="2.4.0" />
</p>

`locals`는 요청의 수명 주기 동안 임의의 정보를 저장하고 액세스하는 데 사용되는 객체입니다. `Astro.locals`는 미들웨어가 설정한 `context.locals` 객체의 모든 값을 포함하는 객체입니다. 이를 사용하여 `.astro` 파일에서 미들웨어가 반환한 데이터에 액세스할 수 있습니다.

미들웨어 함수는 `context.locals`의 값을 읽고 쓸 수 있습니다:

```ts title="src/middleware.ts" "locals"
import type { MiddlewareHandler } from 'astro';

export const onRequest: MiddlewareHandler = ({ locals }, next) => {
  if (!locals.title) {
    locals.title = "Default Title";
  }
  return next();
}
```

Astro 컴포넌트와 API 엔드포인트는 렌더링할 때 `locals`에서 값을 읽을 수 있습니다:

<Tabs>
  <TabItem label="Astro.locals">
    ```astro title="src/pages/Orders.astro" "Astro.locals"
    ---
    const title = Astro.locals.title;
    ---
    <h1>{title}</h1>
    ```
  </TabItem>
  <TabItem label="context.locals">
    ```ts title="src/pages/hello.ts" "locals"
    import type { APIContext } from 'astro';

    export function GET({ locals }: APIContext) {
      return new Response(locals.title); // "Default Title"
    }
    ```
  </TabItem>
</Tabs>

### `preferredLocale`

<p>

**타입:** `string | undefined`<br />
<Since v="3.5.0" />
</p>

`preferredLocale`은 방문자의 브라우저 언어 기본 설정과 사이트에서 지원하는 로케일 간에 가장 잘 일치하는 것을 찾기 위해 계산된 값입니다.

이 값은 [`i18n.locales`](/ko/reference/configuration-reference/#i18nlocales) 배열에 구성된 로케일과 `Accept-Language` 헤더를 통해 사용자의 브라우저에서 지원하는 로케일을 확인하여 계산됩니다. 일치하는 항목이 없으면 이 값은 `undefined`입니다.

이 속성은 요청 시 렌더링되는 경로에서만 사용할 수 있으며 미리 렌더링된 정적 페이지에는 사용할 수 없습니다.

### `preferredLocaleList`

<p>

**타입:** `string[] | undefined`<br />
<Since v="3.5.0" />
</p>

`preferredLocaleList`는 브라우저에서 요청하고 웹사이트에서 지원하는 모든 로케일의 배열을 나타냅니다. 이렇게 하면 사이트와 방문자 간에 호환되는 모든 언어의 목록이 생성됩니다. 

브라우저에서 요청한 언어가 로케일 배열에 없으면 값은 `[]`가 됩니다. 이는 방문자가 선호하는 로케일을 지원하지 않을 때 발생합니다.

브라우저에 기본 설정 언어가 지정되지 않은 경우 이 값은 [`i18n.locales`](/ko/reference/configuration-reference/#i18nlocales)가 되며, 기본 설정이 없는 방문자에게는 지원되는 모든 로케일이 동일하게 기본 설정된 것으로 간주됩니다. 

이 속성은 요청 시 렌더링되는 경로에서만 사용할 수 있으며 미리 렌더링된 정적 페이지에는 사용할 수 없습니다.

### `currentLocale`

<p>

**타입:** `string | undefined`<br />
<Since v="3.5.6" />
</p>

`locales` 구성에 지정된 구문을 사용하여 현재 URL에서 계산된 로케일입니다. URL에 `/[locale]/` 접두사가 포함되지 않았다면 기본값은 [`i18n.defaultLocale`](/ko/reference/configuration-reference/#i18ndefaultlocale)이 됩니다.

### `getActionResult()`

<p>
**타입:** `(action: TAction) => ActionReturnType<TAction> | undefined`<br />
<Since v="4.15.0" />
</p>

`getActionResult()`는 [액션](/ko/guides/actions/) 제출의 결과를 반환하는 함수입니다. 이 함수는 액션 함수(예: `actions.logout`)를 인수로 받아 제출이 수신되면 `data` 또는 `error` 객체를 반환합니다. 그렇지 않으면 `undefined`을 반환합니다.

```astro title="src/pages/index.astro" "Astro.getActionResult"
---
import { actions } from 'astro:actions';

const result = Astro.getActionResult(actions.logout);
---

<form action={actions.logout}>
  <button type="submit">Log out</button>
</form>
{result?.error && <p>Failed to log out. Please try again.</p>}
```

### `callAction()`

<p>
<Since v="4.15.0" />
</p>

`callAction()`은 Astro 컴포넌트에서 액션 핸들러를 직접 호출하는 데 사용되는 함수입니다. 이 함수는 액션 함수를 첫 번째 인수로 받고(예: `actions.logout`), 액션이 수신하는 모든 입력을 두 번째 인수로 받습니다. 이 함수는 액션의 결과를 프로미스로 반환합니다.

```astro title="src/pages/index.astro" "Astro.callAction"
---
import { actions } from 'astro:actions';

const { data, error } = await Astro.callAction(actions.logout, { userId: '123' });
---
```

### `routePattern`

<p>

**타입**: `string`<br />
<Since v="5.0.0" />
</p>

현재 페이지 또는 경로를 생성하는 경로 패턴입니다. 파일 기반 라우팅에서는 경로를 생성하는 데 사용되는 프로젝트의 파일 경로와 유사합니다. 통합이 프로젝트의 경로를 생성하는 경우 `context.routePattern`은 `injectRoute.pattern`의 값과 동일합니다.

이 값은 선행 슬래시로 시작하며 파일 확장자가 없는 `src/pages/` 폴더를 기준으로 한 페이지 컴포넌트의 경로와 유사하게 표시됩니다.

예를 들어, `src/pages/en/blog/[slug].astro` 파일은 `routePattern`에 대해 `/en/blog/[slug]`를 반환합니다. 해당 파일에 의해 생성된 사이트의 모든 페이지(예: `/en/blog/post-1/`, `/en/blog/post-2/` 등)는 `routePattern`에 대해 동일한 값을 공유합니다. `index.*` 경로의 경우, 경로 패턴에 "index."라는 단어가 포함되지 않습니다. 예를 들어 `src/pages/index.astro`는 `/`를 반환합니다.

이 속성을 사용하여 컴포넌트를 렌더링하는 경로를 파악할 수 있습니다. 이를 통해 유사하게 생성된 페이지 URL을 함께 타겟팅하거나 분석할 수 있습니다. 예를 들어 특정 정보를 조건부로 렌더링하거나 어떤 경로가 느린지에 대한 메트릭을 수집하는 데 사용할 수 있습니다.

### `cookies`

<p>

**타입:** `AstroCookies`<br />
<Since v="1.4.0" />
</p>

`cookies`에는 [요청 시 렌더링되는 경로](/ko/guides/on-demand-rendering/)에 대한 쿠키를 읽고 조작하기 위한 유틸리티가 포함되어 있습니다.

#### 쿠키 유틸리티

##### `cookies.get()`

<p>

**타입:** <code>(key: string, options?: <a href="#astrocookiegetoptions">AstroCookieGetOptions</a>) => <a href="#astrocookie-타입">AstroCookie</a> | undefined</code>
</p>

쿠키를 [`AstroCookie`](#astrocookie-타입) 객체로 가져옵니다. 이 객체에는 `value`와 쿠키를 문자열이 아닌 타입으로 변환하기 위한 유틸리티 함수가 포함되어 있습니다.

##### `cookies.has()`

<p>

**타입:** <code>(key: string, options?: <a href="#astrocookiegetoptions">AstroCookieGetOptions</a>) => boolean</code>
</p>

이 쿠키가 존재하는지 여부. 쿠키가 `Astro.cookies.set()`을 통해 설정된 경우 true를 반환하고, 그렇지 않으면 `Astro.request`에서 쿠키를 확인합니다.

##### `cookies.set()`

<p>

**타입:** <code>(key: string, value: string | object, options?: <a href="#astrocookiesetoptions">AstroCookieSetOptions</a>) => void</code>
</p>

쿠키의 `key`를 지정된 값으로 설정합니다. 쿠키 값을 문자열로 변환하려고 시도합니다. 옵션은 `maxAge` 또는 `httpOnly`와 같은 [쿠키 기능](https://www.npmjs.com/package/cookie#options-1)을 설정하는 방법을 제공합니다.

##### `cookies.delete()`

<p>

**타입:** `(key: string, options?: AstroCookieDeleteOptions) => void`
</p>

만료일을 과거(유닉스 시간 기준 0)로 설정하여 쿠키를 무효화합니다.

쿠키가 "삭제"(만료)되면 `Astro.cookies.has()`는 `false`를 반환하고 `Astro.cookies.get()`은 `value`가 `undefined`인 [`AstroCookie`](#astrocookie-타입)를 반환합니다. 쿠키를 삭제할 때 사용할 수 있는 옵션은 다음과 같습니다: `domain`, `path`, `httpOnly`, `sameSite`, `secure`.

##### `cookies.merge()`

<p>

**타입:** `(cookies: AstroCookies) => void`
</p>

새 `AstroCookies` 인스턴스를 현재 인스턴스에 병합합니다. 새 쿠키가 현재 인스턴스에 추가되고 같은 이름의 쿠키가 있으면 기존 값을 덮어씁니다.

##### `cookies.headers()`

<p>

**타입:** `() => Iterator<string>`
</p>

응답과 함께 전송될 `Set-Cookie`의 헤더 값을 가져옵니다.

#### `AstroCookie` 타입

`Astro.cookies.get()`을 통해 쿠키를 가져올 때 반환되는 타입입니다. 다음과 같은 속성을 가집니다:

##### `value`

<p>

**타입:** `string`
</p>

쿠키의 원시 문자열 값입니다.

##### `json`

<p>

**타입:** `() => Record<string, any>`
</p>

`JSON.parse()`를 통해 쿠키 값을 구문 분석하여 객체를 반환합니다. 쿠키 값이 유효한 JSON이 아닐 경우 오류가 발생합니다.

##### `number`

<p>

**타입:** `() => number`
</p>

쿠키 값을 숫자로 구문 분석합니다. 유효한 숫자가 아닌 경우 NaN을 반환합니다.

##### `boolean`

<p>

**타입:** `() => boolean`
</p>

쿠키 값을 부울로 변환합니다.

#### `AstroCookieGetOptions`

<p><Since v="4.1.0"/></p>

`AstroCookieGetOption` 인터페이스를 사용하면 쿠키를 받을 때 옵션을 지정할 수 있습니다.

##### `decode`

<p>
**타입:** `(value: string) => string`
</p>

쿠키가 값으로 역직렬화되는 방식을 사용자 지정할 수 있습니다.

#### `AstroCookieSetOptions`

<p><Since v="4.1.0"/></p>

`AstroCookieSetOptions`는 쿠키를 설정할 때 `Astro.cookies.set()`에 전달하여 쿠키 직렬화 방식을 사용자 지정할 수 있는 객체입니다.

##### `domain`

<p>

**타입:** `string`
</p>

도메인을 지정합니다. 도메인을 설정하지 않으면 대부분의 클라이언트는 현재 도메인에 적용되는 것으로 해석합니다.

##### `expires`

<p>

**타입:** `Date`
</p>

쿠키가 만료되는 날짜를 지정합니다.

##### `httpOnly`

<p>

**타입:** `boolean`
</p>

true이면 클라이언트 측에서 쿠키에 액세스할 수 없습니다.

##### `maxAge`

<p>

**타입:** `number`
</p>

쿠키가 유효한 기간(초)을 숫자로 지정합니다.

##### `path`

<p>

**타입:** `string`
</p>

쿠키가 적용되는 도메인의 하위 경로를 지정합니다.

##### `sameSite`

<p>

**타입:** `boolean | 'lax' | 'none' | 'strict'`
</p>

[SameSite](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-rfc6265bis-09#section-5.4.7) 쿠키 헤더의 값을 지정합니다.

##### `secure`

<p>

**타입:** `boolean`
</p>

true인 경우 쿠키는 https 사이트에만 설정됩니다.

##### `encode`

<p>

**타입:** `(value: string) => string`
</p>

쿠키가 직렬화되는 방식을 사용자 지정할 수 있습니다.

### `session`

<p>

**타입:** `AstroSession`

<Since v="5.7.0" />

</p>

[요청 시 렌더링되는 라우트](/ko/guides/on-demand-rendering/)에 대해 요청 간 데이터를 저장할 수 있게 해주는 객체가 바로 `session`입니다. 세션 자체의 데이터는 쿠키에 저장되지 않고, 세션 ID만 담고 있는 쿠키와 연결됩니다.

세션은 처음 사용될 때 생성되며, 세션 쿠키는 자동으로 설정됩니다. 세션 스토리지가 구성되지 않았거나 현재 라우트가 사전 렌더링된 경우에는 `session` 객체가 `undefined`가 되며, 이를 사용하려고 하면 오류가 기록됩니다.

Astro 프로젝트에서 세션을 사용하는 방법에 대한 더 자세한 내용은 [세션 가이드](/ko/guides/sessions/)를 참조하세요.

#### `get()`

<p>

**타입**: `(key: string) => Promise<any>`

</p>

세션에서 주어진 키에 해당하는 값을 반환합니다. 해당 키가 존재하지 않으면 `undefined`를 반환합니다.

<Tabs>
  <TabItem label="Astro.session">
    ```astro title="src/components/Cart.astro" "Astro.session?.get('cart')"
    ---
    const cart = await Astro.session?.get('cart');
    ---
    <button>🛒 {cart?.length}</button>
    ```
  </TabItem>
  <TabItem label="context.session">
    ```ts title="src/pages/api/cart.ts" "session.get('cart')"
    import type { APIContext } from 'astro';

    export async function GET({ session }: APIContext) {
      const cart = await session.get('cart');
      return Response.json({ cart });
    }
    ```

  </TabItem>
</Tabs>

#### `set()`

<p>

**타입**: `(key: string, value: any, options?: { ttl: number }) => void`

</p>

세션에서 주어진 키에 해당하는 값을 설정합니다. 값은 직렬화 가능한 어떤 타입이든 가능합니다. 이 메서드는 동기적이며, 설정된 값은 즉시 검색할 수 있지만, 요청이 끝날 때까지 백엔드에 저장되지는 않습니다.

<Tabs>
  <TabItem label="Astro.session">
    ```astro title="src/pages/products/[slug].astro" "Astro.session?.set('lastViewedProduct', slug)"
    ---
    const { slug } = Astro.params;
    Astro.session?.set('lastViewedProduct', slug);
    ---
    ```
  </TabItem>
  <TabItem label="context.session">
    ```ts title="src/pages/api/add-to-cart.ts" "session.set('cart', cart)"
    import type { APIContext } from 'astro';

    export async function POST({ session, request }: APIContext) {
      const cart = await session.get('cart');
      const newItem = await request.json();
      cart.push(newItem);
      // 업데이트된 장바구니를 세션에 저장합니다.
      session.set('cart', cart);
      return Response.json({ cart });
    }
    ```

  </TabItem>
</Tabs>

#### `regenerate()`

<p>

**타입**: `() => void`

</p>

세션 ID를 갱신합니다. 세션 고정 공격을 방지하기 위해 사용자가 로그인하거나 권한이 상승했을 때 호출하세요.

<Tabs>
  <TabItem label="Astro.session">
    ```astro title="src/pages/welcome.astro" "Astro.session?.regenerate()"
    ---
    Astro.session?.regenerate();
    ---
    ```
  </TabItem>
  <TabItem label="context.session">
    ```ts title="src/pages/api/login.ts" "session.regenerate()"
    import type { APIContext } from 'astro';

    export async function POST({ session }: APIContext) {
      // 사용자를 인증합니다...
      doLogin();
      // 세션 고정 공격을 방지하기 위해 세션 ID를 갱신합니다.
      session.regenerate();
      return Response.json({ success: true });
    }
    ```

  </TabItem>
</Tabs>

#### `destroy()`

<p>

**타입**: `() => void`

</p>

세션을 파기합니다. 쿠키와 백엔드에 있는 객체를 모두 삭제합니다. 사용자가 로그아웃하거나 세션이 무효화되었을 때 호출하세요.

<Tabs>
  <TabItem label="Astro.session">
    ```astro title="src/pages/logout.astro" "Astro.session?.destroy()"
    ---
    Astro.session?.destroy();
    return Astro.redirect('/login');
    ---
    ```
  </TabItem>
  <TabItem label="context.session">
    ```ts title="src/pages/api/logout.ts" "session.destroy()"
    import type { APIContext } from 'astro';

    export async function POST({ session }: APIContext) {
      session.destroy();
      return Response.json({ success: true });
    }
    ```

  </TabItem>
</Tabs>

#### `load()`

<p>

**타입**: `(id: string) => Promise<void>`
</p>

ID를 사용하여 세션을 로드합니다. 일반적인 사용 환경에서는 요청 쿠키로부터 세션이 자동으로 로드됩니다. 이 메서드는 다른 ID의 세션을 로드해야 할 때 사용합니다. 세션 ID를 직접 관리하거나, 쿠키를 사용하지 않고 세션을 추적하고 싶을 때 유용합니다.

<Tabs>
  <TabItem label="Astro.session">
    ```astro title="src/pages/cart.astro" "Astro.session?.load('session-id')"
    ---
    // 헤더에서 쿠키 대신 세션을 로드합니다.
    const sessionId = Astro.request.headers.get('x-session-id');
    await Astro.session?.load(sessionId);
    const cart = await Astro.session?.get('cart');
    ---
    <h1>Your cart</h1>
    <ul>
      {cart?.map((item) => (
        <li>{item.name}</li>
      ))}
    </ul>
    ```
  </TabItem>
  <TabItem label="context.session">
    ```ts title="src/pages/api/load-session.ts" "session.load('session-id')"
    import type { APIRoute } from 'astro';

    export const GET: APIRoute = async ({ session, request }) => {
      // 헤더에서 쿠키 대신 세션을 로드합니다.
      const sessionId = request.headers.get('x-session-id');
      await session.load(sessionId);
      const cart = await session.get('cart');
      return Response.json({ cart });
    };
    ```

  </TabItem>

</Tabs>


### 더 이상 사용되지 않는 객체 속성

#### `Astro.glob()`

:::caution[v5.0에서 더 이상 사용되지 않음]
[Vite의 `import.meta.glob`](https://ko.vite.dev/guide/features.html#glob-import)을 사용하여 프로젝트 파일을 쿼리합니다. 

`Astro.glob('../pages/post/*.md')`를 다음과 같이 변환할 수 있습니다.

`Object.values(import.meta.glob('../pages/post/*.md', { eager: true }));`

더 많은 정보와 사용법은 [가져오기 가이드](/ko/guides/imports/#importmetaglob)를 참조하세요.
:::

`Astro.glob()`은 정적 사이트 설정에 많은 로컬 파일을 로드하는 방법입니다.

```astro
---
// src/components/my-component.astro
const posts = await Astro.glob('../pages/post/*.md'); // ./src/pages/post/*.md에 위치한 게시물의 배열을 반환합니다.
---

<div>
{posts.slice(0, 3).map((post) => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.url}>Read more</a>
  </article>
))}
</div>
```

`.glob()`은 하나의 매개변수만 받습니다: 가져오려는 로컬 파일의 상대 URL. 이 함수는 비동기식이며 일치하는 파일에서 내보낸 값들로 이루어진 배열을 반환합니다.

`.glob()`은 통계적으로 분석할 수 없으므로 변수나 보간하는 문자열을 받을 수 없습니다. (해결 방법은 [가져오기 가이드](/ko/guides/imports/#지원되는-값)를 참조하세요.) 이는 `Astro.glob()`이 Vite의 [`import.meta.glob()`](https://ko.vite.dev/guide/features.html#glob-import)의 래퍼이기 때문입니다.

:::note
다음과 같은 경우 Astro 프로젝트에서 `import.meta.glob()`를 사용할 수도 있습니다:
- API 라우트와 같이 `.astro`가 아닌 파일인 경우. `Astro.glob()`은 `.astro` 파일에서만 사용할 수 있지만 `import.meta.glob()`은 프로젝트의 어느 곳에서나 사용할 수 있습니다.
- 각 파일을 즉시 로드하고 싶지 않은 경우. `import.meta.glob()`은 콘텐츠 자체를 반환하는 대신 파일 콘텐츠를 가져오는 함수를 반환할 수 있습니다. 여기에는 가져온 파일에 대한 모든 스타일과 스크립트가 포함됩니다. 파일이 실제로 사용되는지 여부는 런타임이 아닌 정적 분석에 의해 결정되므로 이러한 파일은 번들로 묶여 페이지에 추가됩니다.
- 각 파일의 경로에 액세스하려는 경우. `import.meta.glob()`은 파일 경로의 콘텐츠 맵을 반환하고 `Astro.glob()`은 콘텐츠 목록을 반환합니다.
- 여러 패턴을 전달하려는 경우(예를 들어, 특정 파일을 필터링하기 위한 "네거티브 패턴" 등을 추가하려는 경우). `import.meta.glob()`는 선택적으로 단일 문자열이 아닌 문자열 배열을 받을 수 있습니다.

[Vite 문서](https://ko.vite.dev/guide/features.html#glob-import)에서 더 자세히 알아보세요.
:::

##### Markdown 파일

`Astro.glob()`으로 가져온 Markdown 파일은 다음과 같은 `MarkdownInstance` 인터페이스를 반환합니다:

```ts
export interface MarkdownInstance<T extends Record<string, any>> {
  /* 이 파일의 YAML/TOML 프런트매터에 지정된 모든 데이터 */
	frontmatter: T;
  /* 이 파일의 절대 경로 */
	file: string;
  /* 이 파일의 렌더링 경로 */
	url: string | undefined;
  /* 이 파일의 콘텐츠를 렌더링하는 Astro 컴포넌트 */
	Content: AstroComponentFactory;
  /** (Markdown 전용) 원시 Markdown 파일 콘텐츠, 레이아웃 HTML 및 YAML/TOML 프런트매터 제외 */
	rawContent(): string;
  /** (Markdown 전용) HTML로 컴파일된 Markdown 파일, 레이아웃 HTML 제외 */
	compiledContent(): string;
  /* 이 파일의 h1...h6 요소의 배열을 반환하는 함수 */
	getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
	default: AstroComponentFactory;
}
```

선택적으로 TypeScript 제네릭을 사용하여 `frontmatter` 변수에 타입을 제공할 수 있습니다.

```astro
---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>
```

##### Astro 파일

Astro 파일에는 다음과 같은 인터페이스가 있습니다:

```ts
export interface AstroInstance {
  /* 이 파일의 파일 경로 */
  file: string;
  /* 이 파일의 URL(pages 디렉터리에 있는 경우) */
	url: string | undefined;
	default: AstroComponentFactory;
}
```

##### 기타 파일

기타 파일에는 다양한 인터페이스가 있을 수 있지만 `Astro.glob()`은 인식할 수 없는 파일 형식이 정확히 무엇인지 알고 있는 경우 TypeScript 제네릭을 허용합니다.

```ts
---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = await Astro.glob<CustomDataFile>('../data/**/*.js');
---
```
